Skip to content

Fix OneNote page create and update contracts - #2570

Closed
lorenzocb wants to merge 5 commits into
UsefulSoftwareCo:mainfrom
lorenzocb:fix/onenote-graph-write-contracts
Closed

lorenzocb wants to merge 5 commits into
UsefulSoftwareCo:mainfrom
lorenzocb:fix/onenote-graph-write-contracts

Conversation

@lorenzocb

@lorenzocb lorenzocb commented Nov 16, 2026 •

Copy link
Copy Markdown

Problem

The generated Microsoft Graph OpenAPI document declares the OneNote page write operations with the wrong request contracts:

  1. POST .../onenote/.../pages declares an application/json microsoft.graph.onenotePage body. Graph rejects JSON for this operation with HTTP 415. The documented contract is a raw text/html body, or multipart/form-data with a required Presentation part (text/html) and optional file parts.
  2. .../pages/{onenotePage-id}/content declares GET and an octet-stream PUT. The documented update is PATCH with an application/json array of patch commands and a 204 response. It is missing.

The OpenAPI invoker already serializes text/html, multipart, and bare-array JSON bodies correctly. Only the spec is wrong.

Change

All code is in packages/plugins/openapi/src/providers/microsoft/graph.ts. It is one more path-item normalization in microsoftGraphKeepPathItem, next to normalizeMicrosoftGraphContentPathItem.

  1. It matches only OneNote page paths under /me, /users/{id}, /groups/{id}, and /sites/{id}, and every nested section form (sections, notebooks/.../sections, sectionGroups/.../sections, notebooks/.../sectionGroups/.../sections, and the root pages collection). That is 20 variants.
  2. POST .../pages: the request body becomes text/html (first, so it is the default) and multipart/form-data (Presentation required, with text/html part encoding; other parts are files). Responses, operationId, and permissions stay.
  3. PATCH .../pages/{onenotePage-id}/content: a JSON array of {target, action, position?, content?} commands with the documented lowercase enums, and a 204 response.
    • The operationId comes from the GET operationId (...GetPagesContent becomes ...PatchPagesContent). It is unique, and it differs from the PUT operationId.
    • Permissions come only from the generated PUT.
    • If the source already declares a PATCH, the documented contract still applies, and the declared operationId stays.
  4. The PUT .../content stays callable, because no evidence shows that it fails on real pages, and removing it can break callers. It is marked deprecated, and its link to the PATCH-only update docs is removed, so tool selection prefers the documented update.
  5. The undocumented onenotePatchContent action does not change.
  6. Path items that are not OneNote (for example drive item content PUT) do not change.
  7. The normalization is idempotent.

How the fix reaches existing integrations

  1. The slice generator (slice-build.ts) and the runtime compile (spec-format-adapter.ts) both use microsoftGraphKeepPathItem. New slices carry the correction. A host that runs this code also corrects slices published before the fix when it compiles them.
  2. Tool calls use the operation bindings that addSpec and updateSpec store (backing.ts). Nothing re-normalizes stored bindings later. An existing integration therefore gets the corrected tools, including the new PATCH tool, at its next spec refresh (updateSpec).
  3. No cache invalidation is necessary. The in-process compiled-spec cache does not apply to the Graph streaming compile path.

Tests

packages/plugins/openapi/src/providers/microsoft/onenote.test.ts uses synthetic Graph-shaped fixtures only.

  1. Spec level, for all 20 variants:
    • corrected create with text/html first;
    • added PATCH with write permissions;
    • deprecated PUT with the request body unchanged;
    • action unchanged;
    • full-graph selection;
    • drive content PUT unchanged;
    • idempotence;
    • a declared PATCH gets corrected and keeps its operationId and write-only permissions.
  2. Slice build: the onenote slice has the corrected operations, unique operationIds, and every $ref resolves.
  3. Runtime through the OpenAPI plugin and the Graph adapter. An integration adds a slice published before the fix, then runs updateSpec. The test then checks the stored tool schemas and the wire requests:
    • Create sends raw text/html.
    • Multipart create sends a Presentation part with Content-Type: text/html, and a file part under its own part name.
    • PATCH sends a bare JSON array to .../pages/{id}/content.

Without the graph.ts change, 4 of the 7 tests fail.

The published service emulators have no OneNote surface. The runtime test therefore serves the fixture and captures requests through an in-memory HttpClient, as the other Graph adapter tests do.

Checks

  1. bun run format:check: pass.
  2. bun run lint: pass.
  3. vitest run in packages/plugins/openapi: 53 files and 344 tests pass, plus the new file.
  4. bun run typecheck: @executor-js/plugin-openapi has no errors. @executor-js/desktop fails locally with a vite/rolldown plugin type mismatch in electron.vite.config.ts, which this change does not touch.
  5. bun run test (with --continue): @executor-js/plugin-openapi passes (53 files, 344 tests). Under full parallel load, five packages had failures, all 5-second timeouts or a build input missing in this local checkout: sdk, execution, local, host-cloudflare, and mcp-apps-shell (pretest build). Run alone, execution (79), local (105), and host-cloudflare (40) pass. The one failing sdk file passes alone (26). This change does not touch these packages.

🤖 Generated with Claude Code

Known limit

The multipart file parts have no fixed names, because the page HTML references them by any part name. The invoker sends a ToolFile value under any part name as a file part, and the test covers this. But the tool input schema does not advertise these extra parts as file inputs, because the extractor rewrites only declared properties. The request body description tells callers how to pass files. A schema hint would need a generic extractor change, which this PR does not make.

Local review record

The local review ran cubic review -b origin/main -j on a clean tree for each round. The reviewed content matches the pushed content. Base: 5d84c5864.

  1. Round 1 at a29e5d9f7: P1, a declared PATCH was not corrected. Fixed in 7625f6e53.
  2. Round 2 at 7625f6e53: P2, multipart file parts are not advertised as file inputs. Partly fixed in 8f346aeb4: the request body description now tells callers how to pass files, and the wire behavior is tested. The schema hint is deferred (see below).
  3. Round 3 at 8f346aeb4: P1, the PATCH could take a read-only scope from a declared PATCH. P2, the delete action was not described. Both fixed in 4dbb0a91f.
  4. Round 4 at 4dbb0a91f (pushed head): two findings, both dismissed with evidence.
    • P1, "PATCH drops path parameters": the runtime wire test resolves onenotePage-id to .../pages/page-1/content.
    • P2, "declared PATCH operationId discarded": the code always keeps a declared operationId, and a test covers it.

Accepted deferral: multipart file part schema hint

  1. Trigger: a caller creates a page with multipart file parts (images or attachments) and relies on the tool input schema to find out how to pass them.
  2. Consequence: the schema does not list extra parts as ToolFile inputs, so a caller might not find this optional attachment input. HTML create, multipart create with Presentation only, and PATCH update are not affected. No data or security risk was found.
  3. Evidence: the invoker sends a ToolFile value under any part name as a file part. The runtime test captures name="image1"; filename="image1.png" with Content-Type: image/png. The request body description documents the ToolFile input.
  4. Cost of a full fix: the extractor would need to rewrite additionalProperties. That is a generic extraction change, out of proportion to this fix.
  5. Revisit when: someone requests attachment support, or a caller cannot find how to pass files.

Out of scope

  1. Misleading messages for HTTP 403 authorization failures.
  2. Generic invoker or extractor changes.
  3. Publishing new slice assets. That follows the merge, through the Graph slices workflow.

lorenzocb and others added 5 commits November 16, 2026 17:20
Empty commit to open the draft PR that carries the plan. The
implementation follows in later commits.

👾 Generated with [Letta Code](https://letta.com)

Co-Authored-By: Letta Code <noreply@letta.com>
Graph's generated OpenAPI document declares a JSON onenotePage body
for POST .../onenote/.../pages. Graph accepts only raw text/html or
multipart/form-data with a Presentation part, and rejects JSON with
HTTP 415. The same document omits the documented PATCH page update
on .../pages/{id}/content and declares an octet-stream PUT instead.

The Graph adapter now corrects these path items in
microsoftGraphKeepPathItem, next to the existing octet-stream
response normalization:

1. Page create takes text/html (first, so it is the default) or
   multipart/form-data with a required text/html Presentation part.
2. Page content gains PATCH with a JSON array of patch commands and a
   204 response. Its operationId derives from the GET operationId, and
   its permissions come from the generated PUT.
3. The generated PUT stays callable for existing callers, but is
   marked deprecated and loses its link to the PATCH-only docs, so
   tool selection prefers the documented update.

The slice generator and the runtime compile share this function, so
new slices carry the fix, and an integration that refreshes its spec
gets corrected tools even from a slice published before the fix.
Non-OneNote paths and the onenotePatchContent action are unchanged.

👾 Generated with [Letta Code](https://letta.com)

Co-Authored-By: Letta Code <noreply@letta.com>
The first version kept a declared PATCH on page content unchanged. A
declared PATCH can carry a generated OData shape, so the documented
contract now always applies. A declared operationId is kept, so its
tool name stays stable and a second pass stays identical.

👾 Generated with [Letta Code](https://letta.com)

Co-Authored-By: Letta Code <noreply@letta.com>
A multipart page create can carry files in parts that the page HTML
references by name. The invoker already sends a ToolFile value under
any part name as a file part, so the test now covers that, and the
request body description tells callers to pass files that way.

👾 Generated with [Letta Code](https://letta.com)

Co-Authored-By: Letta Code <noreply@letta.com>
A declared PATCH could carry a read-only scope, and the corrected
update kept it when the path had no PUT. Permissions now come only
from the generated PUT. The PATCH description also covers the delete
action, which takes no content.

👾 Generated with [Letta Code](https://letta.com)

Co-Authored-By: Letta Code <noreply@letta.com>
@lorenzocb lorenzocb closed this Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant